package ligne2vie.topos.client.service;

import java.util.List;

import ligne2vie.topos.shared.bo.TSummit;

import com.google.gwt.user.client.rpc.RemoteService;
import com.google.gwt.user.client.rpc.RemoteServiceRelativePath;

/**
 * The interface {@link SummitService} defines all the methods required to manage summits.
 * 
 * @author thuguerre
 * @since 1.0.0
 */
@RemoteServiceRelativePath("summit")
public interface SummitService extends RemoteService {

	/**
	 * The method {@link #createSummit(String, int, double, double)} creates and saves a new summit into the database.
	 * All parameters are verified before creating it.
	 * 
	 * @param name
	 *            Summit name. Cannot be null or empty. Is trimed before saved.
	 * @param altitude
	 *            Summit altitude. Cannot be negative, equal to zero, or greater than Everest's altitude.
	 * @param latitude
	 *            Summit latitude.
	 * @param longitude
	 *            Summit longitude.
	 * @param description
	 *            Summit description.
	 * @return The created summit.
	 */
	public TSummit createSummit(String name, int altitude, double latitude, double longitude, String description);

	/**
	 * The method {@link #editSummit(long, String, int, double, double)} edits and saves an existing summit into the
	 * database. All parameters are verified before editing it.
	 * 
	 * @param summitId
	 *            Identifier of the summit to edit.
	 * @param name
	 *            Summit name. Cannot be null or empty. Is trimed before saved.
	 * @param altitude
	 *            Summit altitude. Cannot be negative, equal to zero, or greater than Everest's altitude.
	 * @param latitude
	 *            Summit latitude.
	 * @param longitude
	 *            Summit longitude.
	 * @param description
	 *            Summit description.
	 * @return The edited summit.
	 */
	public TSummit editSummit(long summitId, String name, int altitude, double latitude, double longitude,
			String description);

	/**
	 * The method {@link #findSummitsAround(double, double, double)} finds and returns all summits which are included in
	 * a circle centered on the given latitude and longitude and whose radius is those given.
	 * 
	 * @param latitude
	 *            Circle center latitude.
	 * @param longitude
	 *            Circle center longitude.
	 * @param radius
	 *            Circle radius in kilometers.
	 * @return List of all corresponding summits. Empty but instantiated if there's not.
	 * @since 1.1.0
	 */
	public List<TSummit> findSummitsAround(double latitude, double longitude, double radius);

	/**
	 * The method {@link #getAllSummits()} returns all the summits the application knows, without any filtering. The
	 * number of returned summits could be important and using it could have a bad effect on displaying and client-side
	 * performance. It should be use with attention.
	 * 
	 * @return All known summits.
	 */
	public List<TSummit> getAllSummits();

	/**
	 * The method {@link #getSummit(long)} returns the summit corresponding to the identifier given as parameter.
	 * 
	 * @param summitId
	 *            Identifier of the summit to get.
	 * @return The corresponding summit.
	 */
	public TSummit getSummit(long summitId);

	/**
	 * The method {@link #removeSummit(long)} removes (not definitively) the summit from the database. It might be
	 * recovered later if required.
	 * 
	 * @param summitId
	 *            Identifier of the summit to remove.
	 */
	public void removeSummit(long summitId);
}
